/*
 * Copyright 2008 Max Kugland
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.splink.library.logging {
	import org.splink.library.logging.logoutput.ILogOutput;
	import org.splink.library.logging.logoutput.IOutputFormatter;	

	/**
	 * The basic interface for <code>ILoggerFactory</code> implementations. A default implementation
	 * is the <code>LogFactory</code>.
	 * 
	 * @see LogFactory
	 * @author Max Kugland
	 */
	public interface ILoggerFactory {
		/**
		 * As there can exist many <code>ILoggerFactory</code> implementing objects they need to be
		 * distinguishable. Therefore every <code>ILoggerFactory</code> must implement <code>getId</code>
		 * The default implementation <code>LogFactory</code> id returns "default" by default.
		 * 
		 * @return the <code>ILoggerFactory</code> id
		 */
		function get id() : String;
		/**
		 * If you need more than one <code>ILoggerFactory</code> instance you need to set an id for 
		 * each <code>ILoggerFactory</code> instance you want to use. This might be the case if several
		 * developers work on the same project but each one wants only to see only his own logs.
		 * If you dont set an id the default implementation <code>LogFactory</code> is set to
		 * "default".
		 * 
		 * @param id the <code>ILoggerFactory</code> id
		 */
		function set id(id : String) : void;

		/**
		 * You can specify via <code>setRange</code> which LogLevels will be logged. Its 
		 * possible to change the current <code>LogRange</code> during runtime, all loggers which 
		 * are created afterwards will consider the new <code>LogRange</code>
		 * 
		 * @param range the <code>LogRange</code> which will be logged.
		 * @see Range
		 * @see LogLevel
		 */		function set range(range : LogRange) : void;

		/**
		 * You can specify a base package as an additional filter, to restrict what is logged. All 
		 * logs which occur within the specified package or below are logged, all other logs are
		 * dropped.
		 * 
		 * @param pack the package path, should look alike "org.splink.library.logging"
		 */
		function set basePackage(pack : String) : void;

		/**
		 * Sets the <code>IOutputFormatter</code> which is used within <code>ILogOutput</code> instances
		 * to format the log output. If no <code>IOutputFormatter</code> is set, <code>DefaultOputFormatter</code>
		 * is used to format log messages. the <code>ILoggerFactory</code> informs the <code>ILogger</code> 
		 * instance about the <code>IOutputFormatter</code> and the <code>ILogger</code> configures
		 * all registered <code>ILogOutput</code> instances to use the <code>IOutputFormatter</code>
		 * Its not possible to change the current <code>IOutputFormatter</code> during runtime.
		 * 
		 * @param formatter the <code>IOutputFormatter</code>
		 * @see DefaultOputFormatter 
		 */
		function set ouputFormatter(formatter : IOutputFormatter) : void;

		/**
		 * Adds an <code>ILogOutput</code> implementation to the factory. All added 
		 * <code>ILogOutput</code> implementations will be feeded by the logger with 
		 * <code>LogEvent</code> objects which contain information about the message to log, the 
		 * <code>LogLevel</code> etc. 
		 * Note that an <code>ILogOutput</code> should be added only to one factory.
		 * 
		 * @param logOutput an <code>ILogOutput</code>implementation
		 * @see LogLevel
		 */
		function addLogOutput(logOutput : ILogOutput) : void;

		/**
		 * Creates and returns an <code>ILogger</code> instance. Usally you want to create an 
		 * <code>ILogger</code> in every class you want to log from.
		 * 
		 * @param clazz the class on which the <code>ILogger</code> operates
		 * @return an <code>ILogger</code> instance
		 * 
		 * @throws Error if no <code>LogOutput</code> has been set yet.
		 */
		function getLogger(clazz : Class) : ILogger;
	}
}
